<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>feed4j quickstart</title>
</head>
<body>
<h1>Quickstart</h1>
<p>Per impiegare il parser di feed4j all'interno del tuo software Java devi, come prima cosa, rendere visibile il file <em>feed4j.jar</em> alla tua applicazione, aggiungendolo al CLASSPATH. Siccome feed4j dipende da librerie di terze parti, i cui jar si trovano nella cartella <em>lib</em> del pacchetto di ditribuzione, anche queste devono essere aggiunte al CLASSPATH.</p>
<h2>Requisiti</h2>
<p>feed4j richiede un ambiente di esecuzione Java J2SE 1.4 o successivo.</p>
<h2>Il parser dei feed</h2>
<p>L'uso del  parser dei feed  (<em>it.sauronsoftware.feed4j.FeedParser</em>) richiede una sola riga di codice:</p>
<pre>Feed feedRepresentation = FeedParser.parse(feedUrl);</pre>
<p>Dopo aver recuperato la rappresentazione ad oggetti del feed (<em>it.sauronsoftware.feed4j.bean.Feed</em>) puoi attivarne i metodi per sapere qualsiasi cosa contenuta nell'XML elaborato. La rappresentazione del feed &egrave; divisa in due parti principali: una intestazione del feed (<em>header</em>) ed una collezione di notizie (<em>item</em>). L'header fornisce accesso ad informazioni che riguardano il feed nella sua completezza, come il titolo, la descrizione, l'indirizzo di origine e cos&igrave; via. I singoli item rappresentano ciascuno una delle notizie riportate nel feed. Principalmente sono formati da un titolo e da un indirizzo, ma possono anche contenere descrizioni in testo semplice e in HTML, date di pubblicazione e modifica, allegati ed altro ancora.</p>
<p>La rappresentazione ad oggetti di un feed pu&ograve; essere padroneggiata in pochi minuti, basta tenere a portata di mano i relativi javadoc, compresi nel pacchetto di distribuzione di feed4j.</p>
<p>Un esempio veloce e completo:</p>
<pre>package it.sauronsoftware.feed4j.example1;

import java.net.URL;

import it.sauronsoftware.feed4j.FeedParser;
import it.sauronsoftware.feed4j.bean.Feed;
import it.sauronsoftware.feed4j.bean.FeedHeader;
import it.sauronsoftware.feed4j.bean.FeedItem;

public class FeedExample {

	public static void main(String[] args) throws Exception {
		
		URL url = new URL(&quot;http://www.scarletgothica.com/rss_it.php&quot;);
		
		Feed feed = FeedParser.parse(url);
		
		System.out.println(&quot;** HEADER **&quot;);
		FeedHeader header = new FeedHeader();
		System.out.println(&quot;Title: &quot; + header.getTitle());
		System.out.println(&quot;Link: &quot; + header.getLink());
		System.out.println(&quot;Description: &quot; + header.getDescription());
		System.out.println(&quot;Language: &quot; + header.getLanguage());
		System.out.println(&quot;PubDate: &quot; + header.getPubDate());
		
		System.out.println(&quot;** ITEMS **&quot;);
		int items = feed.getItemCount();
		for (int i = 0; i &lt; items; i++) {
			FeedItem item = feed.getItem(i);
			System.out.println(&quot;Title: &quot; + item.getTitle());
			System.out.println(&quot;Link: &quot; + item.getLink());
			System.out.println(&quot;Plain text description: &quot; + item.getDescriptionAsText());
			System.out.println(&quot;HTML description: &quot; + item.getDescriptionAsHTML());
			System.out.println(&quot;PubDate: &quot; + item.getPubDate());
		}
		
	}

}</pre>
<p>Un esempio un po' pi&ugrave; complesso &egrave; nella cartella <em>examples/example2</em> del pacchetto di distribuzione della libreria.</p>
<h2>Intercettare le eccezioni</h2>
<p>Il metodo <em>FeedParser.parse()</em> pu&ograve; lanciare diversi tipi di eccezione, in base al problema riscontrato:</p>
<ul>
  <li><em>FeedIOException</em>: il feed non pu&ograve; essere recuperato a causa di un problema I/O.</li>
  <li><em>FeedXMLParseException</em>: il file &egrave; stato recuperato, ma il suo contenuto non &egrave; un XML valido.</li>
  <li><em>UnsupportedFeedException</em>: il file &egrave; stato recuperato, il suo contenuto &egrave; risultato essere un XML valido, ma la struttura al suo interno non rispecchia nessuno dei formati di feed supportati da feed4j.</li>
</ul>
<p>Poich&eacute; queste eccezioni estendono tutte la classe <em>FeedException</em>, puoi decidere se gestirle una per una o tutte insieme con un solo blocco <em>catch</em>:</p>
<pre>Feed feed;
try {
	feed = FeedParser.parse(feedUrl);
} catch (FeedIOException e) {
	// una
} catch (FeedXMLParseException e) {
	// per
} catch (UnsupportedFeedException e) {
	// una
}

try {
	feed = FeedParser.parse(feedUrl);
} catch (FeedException e) {
	// tutte insieme
}</pre>
<h2>Formati di  feed supportati</h2>
<p>Il parser di feed4j pu&ograve; attualmente interpretare i seguenti formati di feed basati su XML:</p>
<ul>
  <li>RSS 1.0 con supporto per i tag Dublin Core</li>
  <li>RSS 2.0</li>
  <li>RSS 0.91 e 0.92, poich&eacute; un feed RSS 0.91 o 0.92 valido &egrave; anche un feed RSS 2.0 valido </li>
  <li>Atom 0.3</li>
  <li>Atom 1.0 (IETF standard)</li>
</ul>
<h2>Gestire i tag personalizzati</h2>
<p>I feed basati su XML sono flessibili e possono essere estesi con tag personalizzati o di terze parti. Il parser di feed4j ti aiuta nel gestire questi tag dandoti accesso diretto e non strutturato (<em>raw</em>) al loro contenuto. Ad esempio: se gli item presenti nel tuo feed XML contengono un tag di estensione chiamato &quot;phone-number&quot;, il cui namespace &egrave; &quot;http://www.mysite.org/myCustomTags&quot;, puoi accedere al  valore al seguente modo:</p>
<pre>String value = feedItem.getElementValue(
	"http://www.mysite.org/myCustomTags", "phone-number"
);</pre>
<p>Nel pacchetto <em>it.sauronsoftware.feed4j.bean</em> c'&egrave; la classe <em>RawElement</em>, che &egrave; un contenitore di informazioni raw. <em>FeedHeader</em>, <em>FeedItem</em>, <em>FeedImage</em> e <em>FeedEnclosure</em> estendono <em>RawElement</em>, cosicch&eacute; oltre a contenere informazioni strutturate come i titoli, le date, gli indirizzi e le descrizioni, possono anche riportare in modo raw tutte le informazioni non direttamente gestite dal parser. Quindi per ottenere un'informazione standard potrai usare i metodi tipizzati e strutturati come <em>getTitle()</em>, <em>getLink()</em> e <em>getPubDate()</em>, mentre tutti gli elementi di estensione non noti a feed4j possono essere recuperati e gestiti con metodi quali <em>getElement()</em>, <em>getAttribute()</em> e <em>getNode()</em>. Fai riferimento alla documentazione javadoc per una lista dettagliata dei metodi disponibili.</p>
</body>
</html>
